Please also fix the CI, thanks!

Please also fix the CI, thanks!请同时修复 CI，谢谢！

Sorry, it's my fault. I will fix the CI and doc. thank you.

@DemesneGH Hi , I’ve updated the relevant files according to your suggestions and fixed the CI issues.
Would you mind taking a look and reviewing the changes?

For 5.1, "cargo-optee" is not recognized as a cargo subcommand, it is because cargo invokes external binaries in an unexpected way.

For example, cargo optee build is invoked as cargo-optee optee build. This extra "optee" argument causes the subcommand parser to fail.

One workaround is to add a parsing rule or configuration option that discards the first (duplicate) argument:

#[derive(Parser)]
#[command(version, about, long_about = None)]
struct Cli {
    // By stripping the duplicate "optee" argument during subcommand invocation, 
    // this solution maintains compatibility between standalone and cargo-integrated execution modes.
    #[arg(name = "tool_name", hide = true)]
    _tool_name: String,
    #[command(subcommand)]
    commands: Commands,
}

For 5.1, "cargo-optee" is not recognized as a cargo subcommand, it is because cargo invokes external binaries in an unexpected way.

For example, cargo optee build is invoked as cargo-optee optee build. This extra "optee" argument causes the subcommand parser to fail.

One workaround is to add a parsing rule or configuration option that discards the first (duplicate) argument:

#[derive(Parser)]
#[command(version, about, long_about = None)]
struct Cli {
    // By stripping the duplicate "optee" argument during subcommand invocation, 
    // this solution maintains compatibility between standalone and cargo-integrated execution modes.
    #[arg(name = "tool_name", hide = true)]
    _tool_name: String,
    #[command(subcommand)]
    commands: Commands,
}

That makes sense—thank you for the suggestion.

I also noticed that with the previous implementation, running cargo-optee in standalone mode results in the following error:

error: the following required arguments were not provided:
  <tool_name>

For this reason, I believe the following approach is more robust: making _tool_name an optional argument.

#[derive(Debug, Parser)]
#[command(version, about)]
pub struct Cli {
    // By stripping the duplicate "optee" argument during subcommand invocation,
    // this solution maintains compatibility between standalone and cargo-integrated execution modes.
    // When invoked as `cargo optee build`, cargo passes "optee" as the first argument.
    // When invoked as `cargo-optee build`, no extra argument is passed.
    #[arg(name = "tool_name", hide = true)]
    _tool_name: Option<String>,

    #[command(subcommand)]
    pub cmd: Command,
}

This allows the CLI to work correctly in both invocation scenarios without requiring additional conditional logic.

@asir66 Thanks for your effort!
I've checked the implementation in cargo-sgx:

#[derive(Debug, Parser)]
#[clap(bin_name = "cargo")]
#[clap(version = VERSION)]
pub(crate) enum Opts {
    /// Utilities to build sgx program.
    #[clap(name = "sgx")]
    #[clap(version = VERSION)]
    #[clap(action = ArgAction::DeriveDisplayOrder)]
    Sgx(SgxArgs),
}

#[derive(Debug, clap::Args)]
pub(crate) struct SgxArgs {
    #[clap(subcommand)]
    cmd: Command,
}

#[derive(Debug, clap::Subcommand)]
enum Command {
    #[clap(name = "build")]
    Build(BuildCommand),
    #[clap(name = "run")]
    Run(RunCommand),
...
}

It seems cargo-sgx only supports being invoked as cargo-sgx sgx xxx and doesn't support the two scenarios.

Could you help with a brief study of how other cargo subcommands handle this case?

To achieve the goal of "cargo-optee acting as a cargo subcommand," it's good to follow the established principles used by other subcommands. If there is a standard convention, we can implement it in the same way; otherwise, the current implementation is fine.

After reviewing a more canonical Cargo subcommand implementation, I noticed that cargo-fmt handles the Cargo-injected subcommand argument in a different and more robust way.

In cargo-fmt, the implementation explicitly drops the first occurrence of the subcommand name (fmt) at program entry, rather than relying on a positional placeholder in the argument parser. This behavior is intentional and aligns well with Cargo’s external subcommand invocation model.

When Cargo invokes an external subcommand, it follows the convention:

cargo <subcommand> <args...>
→ cargo-<subcommand> <subcommand> <args...>

As a result, a well-behaved Cargo subcommand should ideally support all of the following invocation forms:

• cargo <args...>
• cargo- <args...>
• cargo- <args...>

I verified that cargo-fmt conforms to this convention, while cargo-sgx currently does not handle all of these cases consistently.

For reference, cargo-fmt implements this logic by filtering out the first occurrence of the injected subcommand name at the very beginning of execution:

fn execute() -> i32 {
    // Drop extra `fmt` argument provided by `cargo`.
    let mut found_fmt = false;
    let args = env::args().filter(|x| {
        if found_fmt {
            true
        } else {
            found_fmt = x == "fmt";
            x != "fmt"
        }
    });

    let opts = Opts::parse_from(args);
}

Following the same rationale, I propose adopting an equivalent approach for cargo-optee, by removing the first occurrence of "optee" from the argument list at program entry:

// Drop extra `optee` argument provided by `cargo`.
let mut found_optee = false;
let filtered_args: Vec<String> = env::args()
    .filter(|x| {
        if found_optee {
            true
        } else {
            found_optee = x == "optee";
            x != "optee"
        }
    })
    .collect();

let cli = Cli::parse_from(filtered_args);

This approach avoids introducing Cargo-specific positional arguments into the CLI definition, keeps the argument parsing logic explicit and localized, and ensures consistent behavior across all supported invocation forms.

I believe this pattern is both more idiomatic and better aligned with existing Cargo tooling practices, as demonstrated by cargo-fmt.

This commit performs a structural refactor of cargo-optee to improve
consistency, readability, and long-term maintainability.

Key changes include:

• Extract CLI-related data structures from the main module into a dedicated
  cli.rs module, clarifying responsibilities and improving modularity.

• Normalize cargo subcommand behavior by stripping the duplicated optee
  argument at program entry, aligning with standard Cargo custom subcommand
  conventions.

• Introduce resolve_project_path to properly resolve and normalize the
  project path into an absolute path.

• Unify directory switching logic in both ca_builder and ta_builder
  by using a shared ChangeDirectoryGuard from the common module.

• Centralize target configuration handling in the common.rs crate and replace
  ad-hoc logic with a strongly-typed enum-based design. A unified
  get_target_and_cross_compile function is introduced for target resolution.

• Add a shared get_target_directory_from_metadata helper in the common
  module to consistently derive the Cargo target directory.

• Introduce join_and_check and join_format_and_check helpers to safely
  join and validate filesystem paths.

• Provide a unified get_package_name helper in the common module for
  consistent package name resolution across modules.

• Replace boolean flags with a strongly-typed ComponentType enum to improve
  clarity and extensibility.

• Reorganize functions across modules following a top-down (call-order)
  layout to improve code readability.

• Fix CI failures in std mode by adjusting the Cargo.toml configuration of
  std-only examples.

I think we can merge it after the changes are made. This PR has been open for a long time, so we can ship the tool first, let developers try it, get feedback, and gradually improve it.

@ivila Sure, I think it's good to merge it before the next release (around Jan 30). I will quickly review it these days.

Once the remaining comments resolved, I believe this PR is ready to merge. The tool is now feature-complete for building both TA and CA, the CI passes, and the documentation is in place. I think the current version is sufficient for the first publish.

Regarding the goal of user interface design "the cargo-optee build command should provide a seamless interface aligned with the existing cargo build workflow" mentioned by @m4sterchain , I suggest to track that via a new Issue where we can perform the comparison with cargo and cargo-sgx, discuss and plan the next steps without delaying this initial merge.

Summary of Changes

This refactors the configuration resolution system in cargo-optee and improves documentation.

Code Refactoring

1. Decoupled configuration resolution logic

   • Moved TaBuildConfig and CaBuildConfig resolution logic to config.rs module
   • Separated metadata parsing from priority resolution (CLI > metadata > default)
   • Created MetadataConfig struct with resolve() method to handle metadata-only parsing
   • Removed redundant extract_build_config_from_metadata function
   • MetadataConfig::resolve() only parses metadata without handling priorities

2. Improved code organization

   • Consolidated build configuration resolution in a single module
   • Better separation of concerns between metadata parsing and configuration resolution

Documentation Improvements

1. Formatted documentation files

   • Formatted emulate-and-dev-in-docker-std.md and emulate-and-dev-in-docker.md

2. Refactored README.md of cargo-optee

   • Improved Quick Start section for better clarity
   • Enhanced Configuration System section with clearer examples

3. Removed hardcoded configurations

   • Removed hardcoded values from hello_world-rs example's Cargo.toml

Thanks for the follow-up commits!
The refactoring significantly improves the modularity: CLI params => TaBuildConfig::resolve() => TaBuilder::build(config). This separation of logic makes it much easier to maintain.
LGTM and will merge it after CI passes, thanks!

Thank you for your review @DemesneGH @ivila